perm filename DO.RPH[UP,DOC]13 blob sn#467501 filedate 1979-08-20 generic text, type C, neo UTF8
COMMENT ⊗   VALID 00004 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	DO
C00009 00003	DO PROGRAM EXTENSIONS	-- MLB 1 May 79
C00019 00004	EXAMPLES OF EXTENDED DO
C00023 ENDMK
C⊗;
DO

[Discussion of most of the new DO extensions is on pages 3 and 4].

The DO program reads any standard text file and puts the characters
from the file into your input buffer. Then the program exits and the
monitor reads the characters and does the rest.  If this causes a
program to be run, it can then read any of the characters remaining in
the buffer, as can any subsequent programs or the monitor if the
programs return to monitor level with some text still unread.

You can only put as many characters into your buffer as there is room
for.  Nesting DO files doesn't work, but chaining them at monitor level
does.  This avoids the restriction on line length.

DO ignores SOS line numbers and the TAB following them.

DO scans the input file and does some special character conversions (as
well as some other functions discussed later).  The basic conversions
made are:

	<CR>	Ignored.

	<LF>	Ignored.

	↔	Insert a <CR> at this point
		(The monitor usually echoes this as <CR><LF>)

	↓	Insert a <LF> at this point.

	≠	Insert an <ALTMODE> at this point.

	λ	Insert a deferred <CALL> at this point.

	α	Add a <CTRL> bit to the next converted character.

	<VT>	Add a <CTRL> bit to the next converted character.

	β	Add a <META> bit to the next converted character.

	<FF>	Add a <META> bit to the next converted character.

	⊗	<ESCAPE>	("circle-x")

	⊗-	<BREAK>		("circle-x" followed by a minus)

	≡	Quote the next character. (Pass it with no conversion.)

        |        Separates different DO functions (see below)

	?        Takes  the next  character  (other than  RETURN or  LINE)  as a
		 variable name.  Suppose the character is A (i.e., ?A).  If this
		 is  the  first occurrence  of  ?A  in the  file,  DO  types out
		 "A=     " and  waits for you  to type in  a text  string ending
		 with RETURN.  This  string is substituted for  every occurrence
		 of ?A in the file.  (It is also rescanned after it is inserted.)

		NOTE: (1 MAY 79)  The command ?\ has been usurped.  It now is used
		to enable the new extensions to DO.  For details see further on in
		this file.


MULTIPLE DO FILES:

To allow more than one DO function to be stored in the same file (good,
for instance, because small files are inefficient in using disk space,
and other reasons), the vertical bar (|) character can be used as a
separator.  The command
	DO DOFILE(3)
will DO the commands between the second and third | characters in the
file.

Quoting with the equivelance sign (≡) will prevent a bar from
segmenting a function.  The above command will actually DO the third
segment in the file, ignoring such quoting.


LABELED DO FUNCTIONS:

The various function segments in a DO file may be labeled by putting a
label immediately followed by a colon (:) as the first thing in the
segment.  If you wished to label some function "FOO" a portion of your DO
file might contain:
	...|FOO:...|...
where the second ellipsis (...) denotes the function segment labeled
"FOO".  (The label "FOO:" is of course not read as part of the
segment).

To DO a labeled segment enclose the name in parenthesis exactly as you
would for a numbered segment.  In the above example, FOO would be
selected by saying
	DO DOFILE(FOO)

The case (upper or lower) of a label is ignored.  Almost anything
reasonable can be used as a label.  Essentially, it cannot be a number
(because you can't specify it), or empty, or contain a colon or bar.
If you have more than one labeled segment the first one is the one DO
uses.

You can specify a labeled segment with a number in parenthesis, but in
that case the label IS part of the segment.  (The extended \FLUSH.
command can be used in this case, if it's really a problem.)


RUNNING DO:

If you say "R DO" you will get a astrisk or "star" (*) prompt. You may
then type the name of the file you wish to "DO".  You may also say 
"DO <FILENAME>".

If you say "DO <FILENAME>" it arranges things so that if you say "G" to
the editor you get the last DO operation. It also sets it up so that if
you say "DO" with no filename it also tries the last one.  Saying
"DO FOO" will first try "FOO.DO", then try "FOO" if "FOO.DO" doesn't
exist.  Saying "DO FOO." will DO file "FOO".

DO's filename parser is somewhat finicky.


DO PROGRAM EXTENSIONS	-- MLB 1 May 79
This section documents some newly implemented extensions to the DO
program.  Some of these "features" may be flushed, new ones may be
added, others modified.  Since the DO program is inherently limited in
its usefulness some of these bells and whistles may be of fairly
dubious utility.  The next page provides some examples.


THE BRICK
To use the new DO features you must specify a special escape character.
Following the POX convention we will call this escape character the
"brick".  In the following, we will use the backslash character "\" as
the brick character in examples of the new features.  We will also use
BNF style angle brackets to enclose syntactic entities, for example,
<char> will be used to denote any character.

To specify a brick character use the sequence
	?\<char>
This makes the <char> the brick character.  For example, to specify
backslash as the brick character use
	?\\

Previously, ?\ would have been processed as a variable name command (cf
earlier DO documentation).  This sequence is no longer available for
this purpose.  This is the only (downwards) incompatibility with the
old DO program.

Note that each segment in a DO file must set the brick if it uses it.


BRICK COMMAND SYNTAX
The brick character appears as the first character of all the new
commands.  Subsequent characters are scanned to determine the command
and to get any needed arguments, etc.  Then normal processing is
resumed until the brick character is encountered again.

If the command is denoted by a special keyword the keyword is delimited
on the right by a dot character "." and may be in upper and/or lower
case letters.


BRICK COMMAND DESCRIPTIONS
The following commands will be grouped in terms of related function.


SPECIAL CHARACTER GENERATION
These commands are used to cause special characters to appear in the
output.  They are somewhat redundant.  They mostly provide alternates
for the regular DO commands without using obscure characters
themselves.

\CR.		Return (same as ↔)
\LF.		Line (same as ↓)
\ALT.		Alt (same as ≠)
\TAB.		Tab
\VT.		Vertical tab
\FF.		Form
\BS.		Backspace

\C.		Add control bit to following character (same as α and VT)
\M.		Add meta bit to following character (same as β and FORM)
\CM.		Add both control and meta bits to following character

\"<char>	Quotes <char> (like ≡)
		THIS COMMAND WILL NOT QUOTE A VERTICAL BAR CHARACTER

\'<octal>	Generate character with given <octal> code number
\=<decimal>	Generate character with given <decimal> code number
		(In rare cases the user may need to delimit the numbers with \.)

\↑<char>	Generate uparrow style character (eg \↑G gets π)
\?<char>	Generate SOS style character (eg \?G gets lower case g)


SYSTEM CHARACTER GENERATION

\CALL.		Generates a deferred call (same as λ)
\ESC.		Preceeds an ESC or BREAK command (same as ⊗)
		Note: WAITS restricts which escape commands are allowed.
		      Also, they are done when scanned and not passed on.
\CLEAR.		Clears the input buffer (with a CLRBUF UUO).


ACTIVATION TABLE MANIPULATION
These commands alter your activation table with the SETACT UUO.  This
is mostly useful for bypassing the line editor for programs (eg RAID)
which use lots of control characters which are also line editor
commands.

\NOLINED.	Suppresses the line editor (sets the ALLACT bit)
\LINED.		Unsuppresses the line editor (clears the ALLACT bit)
\NOCONBLT.	Suppresses control B, L and T only (sets the SUPCT bit)
\CONBLT.	Unsuppresses control B, L and T only (clears the SUPCT bit)


BRICK CHARACTER MANIPULATION
Actually, ?\<char> pushes the old brick on a stack.  Hence:

\POPBRICK.	Pops the old brick off the stack and makes it the brick


PRINTING

\PRINT.<char><string-sans-char><char>

This command provides a limited printing capability.  It cannot print
characters such as RETURN normally since these are removed from the
input earlier in the scan.

\NEWLINE.	Prints a CR followed by an LF.

\LOADED.<char><string-sans-char><char>

This command is similar to PRINT except that it loads the line editor with
the indicated string.  This should be useful in providing default response
before doing an \INPUT. (see below).


MACRO VARIABLE COMMANDS
There is a set of 128 string variables, whose names are the
corresponding character.  In normal mode scanning these are set with
the ?<char> command.  The following commands allow a limited ammount of
manipulation of these strings.  The symbol <macro> will stand for the
character which is the name of the macro variable.

\←<macro><char><string-sans-char><char>		Sets <macro> to delimited string
\INPUT.<macro>					Inputs <macro> from the terminal
\&<macro1><macro2><macro3>			Like SAIL macro1 ← macro2 & macro3

\INSERT.<macro>		Patches <macro> directly into the output, unlike
			the ?<macro> command which causes it to be rescanned

OUTPUT CONTROL COMMANDS
Output is placed in the input buffer by default.  It can also be
appended to a macro.  In addition, output characters may be "unsaid".

\PUSHOUT.<macro>	Causes subsequent output to be appended to <macro>
\POPOUT.		Returns to previous output destination

\UNSAY.<decimal integer>	Causes given number of characters to be removed
				from the end of the output destination, ie the
				output is "backspaced".  If more characters are
				"unsaid" than are there the result is a \FLUSH.
				See the examples.

\FLUSH.		Essentially "\UNSAY.∞", the destination is completely cleared.


SYNTACTIC COMMANDS

\.					Nothing.  (Can be used to delimit numbers)
\;<char><string-sans-char><char>	Comment, ignores between <char>s


MISCELLANEOUS COMMANDS

\BEEP.		Does a BEEP UUO.
\XYZZY.		Magic.


EXAMPLES OF EXTENDED DO

\;;	This is a typical comment, delimited by semicolons;

\;;	The following generates a string of six equivelance signs (≡'s);
≡≡\"≡\'36\=30\↑↑\?7

\;;	Here we push the brick to get a filehack;
?\$ET \MAIL$POPBRICK.

\;;	This would allow the user to (say) put downarrows around the
	file name without having them turned into LFs by DO;
\PRINT."Filename, please: "\INPUT.F\INSERT.F

\;;	The following uses macro output to reprint its input before DOing it;
\NEWLINE.\PRINT."Type something for me to DO: "\;;	prompt user;
\INPUT.A\;;						get do string;
\PUSHOUT.B\;;						start output to B;
\"\NEWLINE.\"\PRINT.*OK, I will DO \;;	set B to start of a print command;
\INSERT.A*\"\NEWLINE.\;;		insert A, finish print command;
\POPOUT.\;;						return to normal output;
?B\;;							do print command;
?A\;;							do input thing;

\;;	The following is a short SAIL program, FOO.SAI.
	The command DO FOO.SAI is equivelant to EXE FOO.SAI.
	This works because \FLUSH. clears the initial SAIL
	text and the | terminates the DO command.;
BEGIN "FOO"
COMMENT I am my own DO file !  ?\\\FLUSH.EXE FOO.SAI↔|;
PRINT("I am my own DO file !! ");
END "FOO"

\;;	Note that together with labeled DO segments source files may
	now contain easily used and maintained information about their
	own compilation, loading etc.  For example:
BEGIN "FOO"
COMMENT Some relevant DO functions follow:
	(note "follow:" is NOT a label, nor is "SYS:" below)
|COMPILE:COM FOO.SAI↔|SAVE:LOAD FOO.REL/NOSAI/SAVE↔
|SYSTEM:REN SYS:←FOO.DMP↔|RUN:R FOO↔|;
PRINT("YOW!!  I am having FUN!!");
END "FOO";


\;;The following is a DO file to avoid the intricacies of the one line FTP
(admitedly a trivial example).  It does however demonstrate the use of
LOADED (by using the source file name as the default for the destination
file name).  It also gives an example of putting a macro into a PRINT or
LOADED command.;

?\\\PRINT."Local file:  "\INPUT.F\;;	Prompt for local file name	;
\PRINT."Destination file name:  "\;;	Prompt for destination file name;
\PUSHOUT.T\;;				Create a macro (to be executed) ;
\"\LOADED.'\INSERT.F';;			    that has the LOADED command	;
\POPOUT.?T\;;				End the macro and execute it	;
\INPUT.D\;;				Actually input the file name	;
FTP/A {SCORE↑}\INSERT.D←\INSERT.F\CR.\;;Issue the FTP command		;